Quarto-Specific Markdown Features

quarto

markdown

syntax

features

interactive

Complete guide to Quarto’s extended markdown syntax and unique features beyond traditional Markdown

Author

Dario Airoldi

Published

January 16, 2025

Modified

November 3, 2025

Abstract

A comprehensive guide to Quarto’s extended markdown features that go beyond standard Markdown capabilities. This document covers div blocks, fenced divs, CSS classes, grid layouts, callout blocks, code execution, cross-references, figures, tables, mathematical expressions, interactive elements, and custom shortcodes. Essential for leveraging Quarto’s full potential in creating rich, interactive documentation.

Keywords

quarto, markdown, syntax, callouts, divs, cross-references, interactive, shortcodes

2 📖 Overview

Quarto extends standard Markdown with powerful features that enable rich, interactive content creation. This guide covers the unique Quarto markdown syntax that goes beyond traditional Markdown capabilities.

3 🏗️ Div Blocks and Fenced Divs

Quarto introduces fenced divs using ::: syntax, which allows you to apply CSS classes and attributes to blocks of content.

3.1 Basic Div Syntax

::: {.class-name}
Content goes here
:::

3.2 Nested Divs

::::{.outer-container}

:::{.inner-section}
Nested content
:::

:::{.another-section}
More nested content
:::

::::

3.3 Multiple Classes and Attributes

::: {.warning .large-text #warning-section}
This is a warning with multiple classes and an ID
:::

4 🎨 CSS Classes and Styling

Quarto supports extensive CSS integration through class application and custom styling.

4.1 Applying CSS Classes

::: {.text-center}
This text will be centered
:::

::: {.bg-primary .text-white .p-3}
Bootstrap-style classes for background, text color, and padding
:::

4.2 Custom CSS Integration

You can define custom CSS in your _quarto.yml or in separate CSS files:

format:
  html:
    css: styles.css
    theme: cosmo

4.3 Inline Styling

[This text is highlighted]{.highlight}

[Red text]{style="color: red;"}

5 📐 Grid Layouts

Quarto provides powerful grid layout capabilities using Bootstrap’s grid system.

5.1 Basic Grid Structure

::::{.grid}

:::{.g-col-12 .g-col-md-6}
### Left Column
Content for the left side
:::

:::{.g-col-12 .g-col-md-6}
### Right Column
Content for the right side
:::

::::

5.2 Complex Grid Layouts

::::{.grid}

:::{.g-col-12}
### Full Width Header
This spans the entire width
:::

:::{.g-col-12 .g-col-md-4}
### Column 1
First column content
:::

:::{.g-col-12 .g-col-md-4}
### Column 2
Second column content
:::

:::{.g-col-12 .g-col-md-4}
### Column 3
Third column content
:::

::::

5.3 Responsive Breakpoints

:::{.g-col-12 .g-col-sm-6 .g-col-md-4 .g-col-lg-3}
Responsive column that adapts to screen size:

- Mobile: Full width (12 columns)
- Small: Half width (6 columns)
- Medium: One-third width (4 columns)
- Large: One-quarter width (3 columns)
:::

6 💬 Callout Blocks

Quarto provides built-in callout blocks for highlighting important information.

6.1 Standard Callout Types

::: {.callout-note}
## Note
This is a note callout block.
:::

::: {.callout-warning}
## Warning
This is a warning callout block.
:::

::: {.callout-important}
## Important
This is an important callout block.
:::

::: {.callout-tip}
## Tip
This is a tip callout block.
:::

::: {.callout-caution}
## Caution
This is a caution callout block.
:::

6.2 Customized Callouts

::: {.callout-note icon=false}
## Custom Note
Note without an icon
:::

::: {.callout-warning collapse="true"}
## Collapsible Warning
This warning can be expanded/collapsed
:::

7 ⚡ Code Execution

Quarto supports executable code blocks with various engines.

7.1 Python Code Execution

```python
import pandas as pd
import matplotlib.pyplot as plt

# Create sample data
data = {'x': [1, 2, 3, 4], 'y': [2, 4, 6, 8]}
df = pd.DataFrame(data)
print(df)
```

7.2 R Code Execution

```r
# R code block
library(ggplot2)
data <- data.frame(x = 1:10, y = (1:10)^2)
ggplot(data, aes(x, y)) + geom_line()
```

7.3 Code Block Options```python
#| echo: false
#| eval: true
#| warning: false

# This code runs but doesn't show the code, only output
print("Hello, World!")
```

8 🔗 Cross-References

Quarto provides sophisticated cross-referencing capabilities.

8.1 Section References

## Introduction {#sec-intro}

As discussed in @sec-intro, we can reference sections.

8.2 Figure References

![Quarto Logo](logo.png){#fig-logo}

See @fig-logo for the Quarto logo.

8.3 Table References

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

: Sample Table {#tbl-sample}

Refer to @tbl-sample for the data.

9 🖼️ Figures and Tables

Enhanced figure and table capabilities with captions and styling.

9.1 Enhanced Figures

![Caption text](image.png){#fig-example fig-align="center" width="50%"}

9.2 Figure Layouts

::: {#fig-layout layout-ncol=2}

![Image 1](img1.png){#fig-img1}

![Image 2](img2.png){#fig-img2}

Two side-by-side images
:::

9.3 Enhanced Tables

| Feature | Standard Markdown | Quarto |
|---------|-------------------|--------|
| Styling | Limited | Extensive |
| Layout | Basic | Advanced |

: Comparison Table {#tbl-comparison .striped .hover}

10 🧮 Mathematical Expressions

Quarto supports LaTeX math rendering with various display options.

10.1 Inline Math

The equation $E = mc^2$ is Einstein's famous formula.

10.2 Display Math

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

10.3 Numbered Equations

$$
f(x) = \sum_{n=0}^{\infty} \frac{f^{(n)}(a)}{n!}(x-a)^n
$$ {#eq-taylor}

Equation @eq-taylor shows the Taylor series.

11 🎯 Interactive Elements

Quarto supports various interactive content types.

11.1 Tabsets

::: {.panel-tabset}

## Tab 1
Content for tab 1

## Tab 2
Content for tab 2

## Tab 3
Content for tab 3

:::

11.2 Accordions

::: {.panel-tabset group="accordion"}

## Section 1
Accordion content 1

## Section 2
Accordion content 2

:::

12 🏷️ Custom Shortcodes

Quarto allows custom shortcodes for reusable content.

12.1 Built-in Shortcodes





{{< embed notebook.ipynb#fig-plot >}}

12.2 Custom Shortcode Definition

Create _extensions/shortcodes/highlight.lua:

function highlight(args, kwargs, meta)
  local text = pandoc.utils.stringify(args[1])
  return pandoc.RawInline('html', '<mark>' .. text .. '</mark>')
end

Use in markdown:

{{< highlight "This text will be highlighted" >}}

13 ✅ Best Practices

13.1 1. Consistent Styling

Use semantic class names
Maintain consistent spacing with grid layouts
Apply responsive design principles

13.2 2. Accessibility

Always include alt text for images
Use proper heading hierarchy
Ensure sufficient color contrast

13.3 3. Performance

Optimize images for web delivery
Use lazy loading for heavy content
Minimize custom CSS and JavaScript

13.4 4. Maintainability

Document custom CSS classes
Use variables for repeated styling
Keep complex layouts modular

13.5 5. Cross-Platform Compatibility

Test layouts on different screen sizes
Ensure graceful degradation
Use standard web technologies

14 Example: Complete Layout

Here’s a comprehensive example combining multiple Quarto features:

---
title: "Project Dashboard"
format:
  html:
    css: custom.css
    grid:
      sidebar-width: 250px
---

::: {.callout-note}
## Project Status
Current project metrics and updates
:::

::::{.grid}

:::{.g-col-12 .g-col-md-8}

### Main Content

::: {.panel-tabset}

## Overview
Project overview content

## Metrics
Performance metrics

## Reports
Detailed reports

:::

:::

:::{.g-col-12 .g-col-md-4}

### Sidebar

::: {.card}
#### Quick Stats
- Metric 1: 95%
- Metric 2: 1,234
- Metric 3: Active
:::

:::

::::

15 Resources

This guide covers the essential Quarto-specific markdown features that extend beyond standard Markdown. These features enable the creation of sophisticated, interactive, and beautifully styled documentation websites.